Typical HAL PKA use cases for migration

This section provides information about typical HAL PKA use cases for migration.

Note

The usage example below is applicable not only for modular exponentiation, but also for other PKA operations such as addition, subtraction, and more. Simply use the corresponding configuration and function calls for the desired operation.

Use case: PKA in polling mode

This use case describes how to start a PKA operation and retrieve results in polling mode using HAL1 and HAL2.

Sequence diagram

PKA operation in polling mode

@startuml participant "Application" as App participant "PKA" as PKA participant "RNG" as RNG App -> RNG: HAL_RNG_Init() note right : Initialize the RNG handle and associate an instance. App -> PKA: HAL_PKA_Init() note right : Initialize the PKA handle and associate an instance. App -> PKA: HAL_PKA_ModExp() @enduml

Code snippet

HAL1

HAL2 

RNG_HandleTypeDef hrng;
PKA_HandleTypeDef hpka;
PKA_ModExpInTypeDef in;
PKA_ModAddInTypeDef in2;
buffer1[0]     = 0xAA;
buffer1[26]    = 0xAA;
uint8_t *pRes  = &buffer1[1];

/* The RNG is clocked through HAL_RNG_MspInit(),
 which is called by HAL_RNG_Init() */
hrng.Instance = RNG;
HAL_RNG_Init(&hrng);

hpka.Instance = PKA;
HAL_PKA_Init(&hpka);

in.expSize = 24;
in.OpSize  = 24;
in.pOp1    = 0x55;
in.pExp    = 0x17;
in.pMod    = 0xAA;
HAL_PKA_ModExp(&hpka, &in, 5000);

HAL_PKA_ModExp_GetResult(&hpka, pRes);

in2.size = 24;
in2.pOp1 = 0x55;
in2.pOp2 = 0x17;
in2.pOp3 = 0xAA;
HAL_PKA_ModAdd(&hpka, in2, 5000);

HAL_PKA_Arithmetic_GetResult(&hpka, pRes);
.
.
.
.
.
/* The content of the ram may be sensitive;
 if the user wants to clean it, use this function */
HAL_PKA_RAMReset(&hpka);

hal_rng_handle_t hrng;
hal_pka_handle_t hpka;
hal_pka_mod_exp_config_t config;
hal_pka_mod_add_config_t config2;
buffer1[0]         = 0xAA;
buffer1[26]        = 0xAA;
uint8_t *p_result  = &buffer1[1];

/* The PKA requires the RNG clock to be enabled */


HAL_RCC_RNG_EnableClock(void);


HAL_PKA_Init(&hpka, HAL_PKA);

config.exponent_size = 24;
config.operand_size  = 24;
config.p_operand     = 0x55;
config.p_exponent    = 0x17;
config.p_modulus     = 0xAA;
HAL_PKA_SetConfigModExp(&hpka, &config);
HAL_PKA_Compute(&hpka, 5000);
HAL_PKA_GetResultModExp(&hpka, p_result);

config2.size_byte   = 24;
config2.p_operand_1 = 0x55;
config2.p_operand_2 = 0x17;
config2.p_operand_3 = 0xAA;
HAL_PKA_SetConfigModAdd(&hpka, &config2);
HAL_PKA_Compute(&hpka, 5000);
HAL_PKA_GetResultAdd(&hpka, p_result);
.
.
.
.
.
/* The content of the ram may be sensitive;
 if the user wants to clean it, use this function */
HAL_PKA_RAMMassErase(&hpka);

Key changes

  1. In HAL2, the operation is configured using a dedicated configuration structure (for example hal_pka_mod_exp_config_t) before starting the computation.

  2. In HAL2, the computation is started using HAL_PKA_Compute() and the result is retrieved using an operation-specific API.

Use case: PKA in interrupt mode

This use case describes how to start a PKA operation and retrieve results in interrupt mode using HAL1 and HAL2.

Sequence diagram

PKA operation in interrupt mode

@startuml participant "Application" as App participant "PKA" as PKA participant "RNG" as RNG App -> RNG: HAL_RNG_Init() note right : Initialize the RNG handle and associate an instance. App -> PKA: HAL_PKA_Init() note right : Initialize the PKA handle and associate an instance. App -> PKA: HAL_PKA_ModExp_IT() @enduml

Code snippet

HAL1

HAL2 

RNG_HandleTypeDef hrng;
PKA_HandleTypeDef hpka;
PKA_ModExpInTypeDef in;
PKA_ModAddInTypeDef in2;
buffer1[0]     = 0xAA;
buffer1[26]    = 0xAA;
uint8_t *pRes  = &buffer1[1];

/* The RNG is clocked through HAL_RNG_MspInit(),
 which is called by HAL_RNG_Init() */
hrng.Instance = RNG;
HAL_RNG_Init(&hrng);

hpka.Instance = PKA;
HAL_PKA_Init(&hpka);

in.expSize = 24;
in.OpSize  = 24;
in.pOp1    = 0x55;
in.pExp    = 0x17;
in.pMod    = 0xAA;
HAL_PKA_ModExp_IT(&hpka, &in);

/* Wait for the callback function HAL_PKA_OperationCpltCallback() */
HAL_PKA_ModExp_GetResult(&hpka, pRes);

in2.size = 24;
in2.pOp1 = 0x55;
in2.pOp2 = 0x17;
in2.pOp3 = 0xAA;
HAL_PKA_ModAdd_IT(&hpka, in2);

/* Wait for the callback function HAL_PKA_OperationCpltCallback() */
HAL_PKA_Arithmetic_GetResult(&hpka, pRes);
.
.
.
.
.
/* The content of the ram may be sensitive;
 if the user wants to clean it, use this function */
HAL_PKA_RAMReset(&hpka);

hal_rng_handle_t hrng;

hal_pka_handle_t hpka;
hal_pka_mod_exp_config_t config;
hal_pka_mod_add_config_t config2;
buffer1[0]         = 0xAA;
buffer1[26]        = 0xAA;
uint8_t *p_result  = &buffer1[1];

/* The PKA requires the RNG clock to be enabled */


HAL_RCC_RNG_EnableClock(void);


HAL_PKA_Init(&hpka, HAL_PKA);

config.exponent_size = 24;
config.operand_size  = 24;
config.p_operand     = 0x55;
config.p_exponent    = 0x17;
config.p_modulus     = 0xAA;
HAL_PKA_SetConfigModExp(&hpka, &config);
HAL_PKA_Compute_IT(&hpka);
/* Wait for the callback function HAL_PKA_OperationCpltCallback() */
HAL_PKA_GetResultModExp(&hpka, p_result);

config2.size_byte   = 24;
config2.p_operand_1 = 0x55;
config2.p_operand_2 = 0x17;
config2.p_operand_3 = 0xAA;
HAL_PKA_SetConfigModAdd(&hpka, &config2);
HAL_PKA_Compute_IT(&hpka);
/* Wait for the callback function HAL_PKA_OperationCpltCallback() */
HAL_PKA_GetResultAdd(&hpka, p_result);
.
.
.
.
.
/* The content of the ram may be sensitive;
 if the user wants to clean it, use this function */
HAL_PKA_RAMMassErase(&hpka);

Key changes

  1. In HAL2, the operation is started in interrupt mode using HAL_PKA_Compute_IT().

  2. In HAL2, result retrieval is done using an operation-specific API after the completion callback.

  3. The sequence separates operation configuration (HAL_PKA_SetConfigModExp()) from computation start.